<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<body>
XQuery test framework based on Apache XML Beans and JUnit.

<h1>XQuery Test Framework</h1>

<p>This package contains the classes that implement the XQuery test
framework. This framework uses Apache XML Beans to execute the XQuery
and for processing XML, both as parameters to the XQuery and the results.
The framework extends JUnit 4 and so can be run as a JUnit test.</p>

<h2>Writing a Test</h2>

<p>To write a test for an XQuery simply do the following:</p>
<ol>
	<li>Create a test class that sub-classes the AbstractXQTest.</li>
	<li>Declare any common namespaces or parameters in a setup method marked
	with <code>@Before</code> JUnit annotation.</li>
	<li>Add one or more test methods marked with the <code>@Test</code> JUnit
	annotation. In each test method:</li>
	<ol>
		<li>Declare any test specific namespaces or parameters within the test method.</li>
		<li>Execute an XQuery.</li>
		<li>Make assertions about the result of the XQuery transformation.</li>
	</ol>
</ol>

<p><b>Remember:</b> JUnit will create a new instance of the test class for every test
method that is defined. This is why the common namespaces and parameters
should be set in the setup method. This will be called each time and provides
a test "constructor".</p>

<h2>Example File-Based Test</h2>

<p>Generally speaking the simplest way to compose a test is to use fixed input
XML read from a file for each parameter and to compare the result of the
transformation against some expected value, also stored in an XML file. The
XML files may have either been copied/exported from the XQuery editor within
OEPE or simply existing XML files.</p>

<p>The parameters to an XQuery can easily be read from an XML file as the
{@link XQAbstractTest#setParameter(File) setParameter} method takes a
<code>File</code> as a argument and reads the XML from that. In addition to
this the {@link XQAbstractTest#assertEquals(File) assertEquals} method also
takes a <code>File</code> as an argument. The XML will be read from the file
and compared to the result.</p>

<p>The following example shows how to write such a test:</p>

<pre class="code">
{@code
...
import java.io.File;
import org.junit.Before;
import org.junit.Test;
...
public class XQExampleTest extends XQAbstractTest {
	...
	&#064;Before
	public void setup() {
		declareNamespace("test", "http://www.example.org/test");
	}
	...
	&#064;Test
	public void test1 {
		executeQuery(new File("MyTest.xq"));
		setParameter("param1", new File("testdata/MyTest/test1/param1.xml"));
		setParameter("param2", new File("testdata/MyTest/test1/param2.xml"));
		assertEquals(new File("testdata/MyTest/test1/expected-result.xml"));
	}	
}
}
</pre>

<h2>Example Test</h2>

<pre>
{@code
...
import java.io.File;
import org.junit.Before;
import org.junit.Test;
...
public class XQExampleTest extends XQAbstractTest {
	...
	&#064;Before
	public void setup() {
		declareNamespace("test", "http://www.example.org/test");
		setParameter("test", new File("test.xml");
	}
	...
	&#064;Test
	public void test1 {
		executeQuery(new File("test.xq"));
		assertEquals(0, "./test:Test/@testattr", "attrval");
	}	
}
}
</pre>

<h2>Running a Test</h2>

<p>The</p>

<h2>Required Classpath</h2>

<p>This framework uses both Apache XML Beans and JUnit frameworks. It also uses
the WebLogic XQuery implementation. As such in order to build or run an XQuery
test based on this framework the following must be available on the classpath:</p>

<ul>
	<li>The OSB utils library containing this framework</li>
	<li>JUnit 4 Library</li>
	<li>Apache XML Beans library</li>
	<li>WebLogic XQuery implementation library</li>
	<li>WebLogic XQuery and Apache XML Beans interoperation library</li>
	<li>Antlr library (required by the XQuery library)</li>
</ul>

<p>Based on an OSB 11g installation this resulted in the following classpath:</p>

<ul>
	<li><code>libs/osb-utils.jar</code></li>
	<li><code>${eclipse.home}/plugins/org.junit4_4.5.0.v20090824.jar</code></li>
	<li><code>${wl.home}/modules/com.bea.core.xml.xmlbeans_2.2.0.0.jar</code></li>
	<li><code>${wl.home}/modules/com.bea.core.xquery.xmlbeans-interop_1.3.0.0.jar</code></li>
	<li><code>${wl.home}/modules/com.bea.core.xquery_1.3.0.0.jar</code></li>
	<li><code>${wl.home}/modules/com.bea.core.antlr.runtime_2.7.7.jar</code></li>
</ul>

</body>
</html>